---
title: 导入 & 导出
icon: '#pro/FolderSync'
---

<MetaData
  lang="zh-CN"
  isPro
  meta={{
    preset: [{
      client: '@univerjs/preset-docs-advanced',
      locale: '@univerjs/preset-docs-advanced/locales/zh-CN',
      style: '@univerjs/preset-docs-advanced/lib/index.css',
    }],
    plugins: [{
      client: '@univerjs-pro/exchange-client',
      locale: '@univerjs-pro/exchange-client/locale/zh-CN',
      style: '@univerjs-pro/exchange-client/lib/index.css',
      facade: '@univerjs-pro/exchange-client/facade',
    }, {
      client: '@univerjs-pro/docs-exchange-client',
    }],
    server: '是',
  }}
/>

<Callout type="warning" title="注意事项">
  导入导出功能需要 Univer 服务端支持，请确保你已经正确安装并配置了 Univer 服务端。具体请参考：[升级到 Pro](/guides/pro)
</Callout>

导入和导出功能允许用户通过 Univer 服务端将 `.docx` 文件导入到 Univer 文档中，或将文档内容导出为 `.docx` 文件，便于与其他办公软件或平台进行交互。

<Callout title="为什么 Univer 通过后端服务实现导入导出？">
  仅通过前端实现的导入导出无论是从性能还是效果上来说都无法满足企业需求，因此我们提供了后端服务来实现导入导出功能。你可以通过一些开源的 DOCX 解析库将文件解析为符合 `IDocumentData` 接口的数据结构，然后通过 Facade API 将数据导入到 Univer 中。
</Callout>

通过菜单栏的导入入口成功导入后，页面左下角会弹出提示框，显示导入成功的信息，并提供访问导入文档的链接。若默认的导入导出行为无法满足你的需求，请查看[《自定义导入文档》](/guides/recipes/tutorials/custom-import)以了解如何自定义导入行为。

## 预设模式

### 安装

<Callout>
  @univerjs/preset-docs-advanced 的 `UniverDocsAdvancedPreset` 预设在运行时依赖 `UniverDocsDrawingPreset` 预设，请先安装 @univerjs/preset-docs-drawing。
</Callout>

```package-install
npm install @univerjs/preset-docs-drawing @univerjs/preset-docs-advanced
```

### 使用

```typescript
import { UniverDocsAdvancedPreset } from '@univerjs/preset-docs-advanced' // [!code ++]
import UniverPresetDocsAdvancedZhCN from '@univerjs/preset-docs-advanced/locales/zh-CN' // [!code ++]
import { UniverDocsCorePreset } from '@univerjs/preset-docs-core'
import UniverPresetDocsCoreZhCN from '@univerjs/preset-docs-core/locales/zh-CN'
import { UniverDocsDrawingPreset } from '@univerjs/preset-docs-drawing' // [!code ++]
import UniverPresetDocsDrawingZhCN from '@univerjs/preset-docs-drawing/locales/zh-CN' // [!code ++]
import { createUniver, LocaleType, mergeLocales } from '@univerjs/presets'

import '@univerjs/preset-docs-core/lib/index.css'
import '@univerjs/preset-docs-drawing/lib/index.css' // [!code ++]
import '@univerjs/preset-docs-advanced/lib/index.css' // [!code ++]

const { univerAPI } = createUniver({
  locale: LocaleType.ZH_CN,
  locales: {
    [LocaleType.ZH_CN]: mergeLocales(
      UniverPresetDocsCoreZhCN,
      UniverPresetDocsDrawingZhCN, // [!code ++]
      UniverPresetDocsAdvancedZhCN, // [!code ++]
    ),
  },
  presets: [
    UniverDocsCorePreset(),
    UniverDocsDrawingPreset(), // [!code ++]
    UniverDocsAdvancedPreset({ // [!code ++]
      universerEndpoint: 'http://localhost:3010', // [!code ++]
    }), // [!code ++]
  ],
})
```

如果你拥有 Univer 的商业许可证，请参考[在客户端使用许可证](/guides/pro/license#在预设模式中使用)进行配置。

### 预设与配置

`UniverSheetsAdvancedPreset` 配置项：

```typescript
interface IUniverSheetsAdvancedPresetConfig {
  // Univer Server 的端口地址
  universerEndpoint?: string
}
```

## 插件模式

### 安装

```package-install
npm install @univerjs-pro/exchange-client @univerjs-pro/docs-exchange-client
```

### 使用

```typescript
import { UniverDocsExchangeClientPlugin } from '@univerjs-pro/docs-exchange-client' // [!code ++]
import { UniverExchangeClientPlugin } from '@univerjs-pro/exchange-client' // [!code ++]
import ExchangeClientZhCN from '@univerjs-pro/exchange-client/locale/zh-CN' // [!code ++]
import { LocaleType, mergeLocales, Univer } from '@univerjs/core'

import '@univerjs-pro/exchange-client/facade' // [!code ++]

import '@univerjs-pro/exchange-client/lib/index.css' // [!code ++]

const univer = new Univer({
  locale: LocaleType.ZH_CN,
  locales: {
    [LocaleType.ZH_CN]: mergeLocales(
      ExchangeClientZhCN, // [!code ++]
    ),
  },
})

const UNIVER_SERVER_ENDPOINT = `http://localhost:8000` // [!code ++]

univer.registerPlugin(UniverExchangeClientPlugin, { // [!code ++]
  uploadFileServerUrl: `${UNIVER_SERVER_ENDPOINT}/universer-api/stream/file/upload`, // [!code ++]
  importServerUrl: `${UNIVER_SERVER_ENDPOINT}/universer-api/exchange/{type}/import`, // [!code ++]
  exportServerUrl: `${UNIVER_SERVER_ENDPOINT}/universer-api/exchange/{type}/export`, // [!code ++]
  getTaskServerUrl: `${UNIVER_SERVER_ENDPOINT}/universer-api/exchange/task/{taskID}`, // [!code ++]
  signUrlServerUrl: `${UNIVER_SERVER_ENDPOINT}/universer-api/file/{fileID}/sign-url`, // [!code ++]
  downloadEndpointUrl: `${UNIVER_SERVER_ENDPOINT}/`, // [!code ++]
}) // [!code ++]
univer.registerPlugin(UniverDocsExchangeClientPlugin) // [!code ++]
```

如果你拥有 Univer 的商业许可证，请参考[在客户端使用许可证](/guides/pro/license#在插件模式中使用)进行配置。

### 插件与配置

`UniverExchangeClientPlugin` 配置项：

```typescript
interface IUniverExchangeClientConfig {
  // Univer Server 的配置
  downloadEndpointUrl?: string
  uploadFileServerUrl?: string
  importServerUrl?: string
  exportServerUrl?: string
  getTaskServerUrl?: string
  signUrlServerUrl?: string
  // 最大超时时间，单位为毫秒
  maxTimeoutTime?: number
}
```

## Facade API

### 导入

#### 导入 `.docx` 文件并获取 `unitId`

<Callout type="warning" title="注意事项">
  此方法仅适用于启用了协同编辑的文档导入。
</Callout>

在启用协同编辑的时候，每个文档都有一个唯一的 `unitId`。使用 `univerAPI.importDOCXToUnitIdAsync` 传入 `file` 参数会返回 `unitId`，可以通过 `unitId` 来访问文档。 `file` 参数可以是一个 `File` 对象，也可以是远程文件的 URL。

```typescript
// 接受 File 对象
const unitId = await univerAPI.importDOCXToUnitIdAsync(file)
// 或者接受远程文件的 URL
// const unitId = await univerAPI.importDOCXToUnitIdAsync('https://example.com/filename.docx');

// 配合协同编辑自动加载数据一同使用 https://docs.univer.ai/zh-CN/guides/docs/features/collaboration#loading-collaborative-documents
const url = new URL(window.location.href)
url.searchParams.set('unit', unitId)
url.searchParams.set('type', '1') // 1 的意思是 String(UniverInstanceType.UNIVER_DOC)
window.location.href = url.toString()

// 或者调用API: univerAPI.loadServerUnit(unitId, 1) 加载文档，具体参数参考 https://reference.univer.ai/zh-CN/classes/FUniver#loadserverunit
```

#### 导入 `.docx` 文件并获取 `IDocumentData`

使用 `univerAPI.importDOCXToSnapshotAsync` 导入 `.docx` 文件，会返回 `IDocumentData` 格式的文档数据。

```typescript
// 接受 File 对象
const snapshot = await univerAPI.importDOCXToSnapshotAsync(file)
// 或者接受远程文件的 URL
// const snapshot = await univerAPI.importDOCXToSnapshotAsync('https://example.com/filename.xlsx');

// 通过快照创建一个新的文档
univerAPI.createUniverDoc(snapshot)
```

### 导出

#### 通过 `unitId` 导出 `.docx` 文件

在启用协同编辑的时候，每个文档都有一个唯一的 `unitId`。使用 `univerAPI.exportDOCXByUnitIdAsync` 传入 `unitId` 参数会返回 `File` 对象。

```typescript
import { downloadFile } from '@univerjs-pro/exchange-client'

const fDocument = univerAPI.getActiveDocument()
const unitId = fDocument.getId()
const file = await univerAPI.exportDOCXByUnitIdAsync(unitId)

// 下载文件
downloadFile(file, 'univer', 'docx')
```

#### 通过 `IDocumentData` 导出 `.docx` 文件

使用 `univerAPI.exportDOCXBySnapshotAsync` 传入 `IDocumentData` 会返回 `File` 对象。

```typescript
import { downloadFile } from '@univerjs-pro/exchange-client'

const fDocument = univerAPI.getActiveDocument()
const snapshot = fDocument.getSnapshot()
const file = await univerAPI.exportDOCXBySnapshotAsync(snapshot)

// 下载文件
downloadFile(file, 'univer', 'docx')
```
